home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-desktop-9.10-i386-PL.iso / casper / filesystem.squashfs / usr / lib / python2.6 / inspect.py < prev    next >
Text File  |  2009-11-02  |  38KB  |  958 lines
  1. # -*- coding: iso-8859-1 -*-
  2. """Get useful information from live Python objects.
  3.  
  4. This module encapsulates the interface provided by the internal special
  5. attributes (func_*, co_*, im_*, tb_*, etc.) in a friendlier fashion.
  6. It also provides some help for examining source code and class layout.
  7.  
  8. Here are some of the useful functions provided by this module:
  9.  
  10.     ismodule(), isclass(), ismethod(), isfunction(), isgeneratorfunction(),
  11.         isgenerator(), istraceback(), isframe(), iscode(), isbuiltin(),
  12.         isroutine() - check object types
  13.     getmembers() - get members of an object that satisfy a given condition
  14.  
  15.     getfile(), getsourcefile(), getsource() - find an object's source code
  16.     getdoc(), getcomments() - get documentation on an object
  17.     getmodule() - determine the module that an object came from
  18.     getclasstree() - arrange classes so as to represent their hierarchy
  19.  
  20.     getargspec(), getargvalues() - get info about function arguments
  21.     formatargspec(), formatargvalues() - format an argument spec
  22.     getouterframes(), getinnerframes() - get info about frames
  23.     currentframe() - get the current stack frame
  24.     stack(), trace() - get info about frames on the stack or in a traceback
  25. """
  26.  
  27. # This module is in the public domain.  No warranties.
  28.  
  29. __author__ = 'Ka-Ping Yee <ping@lfw.org>'
  30. __date__ = '1 Jan 2001'
  31.  
  32. import sys
  33. import os
  34. import types
  35. import string
  36. import re
  37. import dis
  38. import imp
  39. import tokenize
  40. import linecache
  41. from operator import attrgetter
  42. from collections import namedtuple
  43.  
  44. # These constants are from Include/code.h.
  45. CO_OPTIMIZED, CO_NEWLOCALS, CO_VARARGS, CO_VARKEYWORDS = 0x1, 0x2, 0x4, 0x8
  46. CO_NESTED, CO_GENERATOR, CO_NOFREE = 0x10, 0x20, 0x40
  47. # See Include/object.h
  48. TPFLAGS_IS_ABSTRACT = 1 << 20
  49.  
  50. # ----------------------------------------------------------- type-checking
  51. def ismodule(object):
  52.     """Return true if the object is a module.
  53.  
  54.     Module objects provide these attributes:
  55.         __doc__         documentation string
  56.         __file__        filename (missing for built-in modules)"""
  57.     return isinstance(object, types.ModuleType)
  58.  
  59. def isclass(object):
  60.     """Return true if the object is a class.
  61.  
  62.     Class objects provide these attributes:
  63.         __doc__         documentation string
  64.         __module__      name of module in which this class was defined"""
  65.     return isinstance(object, types.ClassType) or hasattr(object, '__bases__')
  66.  
  67. def ismethod(object):
  68.     """Return true if the object is an instance method.
  69.  
  70.     Instance method objects provide these attributes:
  71.         __doc__         documentation string
  72.         __name__        name with which this method was defined
  73.         im_class        class object in which this method belongs
  74.         im_func         function object containing implementation of method
  75.         im_self         instance to which this method is bound, or None"""
  76.     return isinstance(object, types.MethodType)
  77.  
  78. def ismethoddescriptor(object):
  79.     """Return true if the object is a method descriptor.
  80.  
  81.     But not if ismethod() or isclass() or isfunction() are true.
  82.  
  83.     This is new in Python 2.2, and, for example, is true of int.__add__.
  84.     An object passing this test has a __get__ attribute but not a __set__
  85.     attribute, but beyond that the set of attributes varies.  __name__ is
  86.     usually sensible, and __doc__ often is.
  87.  
  88.     Methods implemented via descriptors that also pass one of the other
  89.     tests return false from the ismethoddescriptor() test, simply because
  90.     the other tests promise more -- you can, e.g., count on having the
  91.     im_func attribute (etc) when an object passes ismethod()."""
  92.     return (hasattr(object, "__get__")
  93.             and not hasattr(object, "__set__") # else it's a data descriptor
  94.             and not ismethod(object)           # mutual exclusion
  95.             and not isfunction(object)
  96.             and not isclass(object))
  97.  
  98. def isdatadescriptor(object):
  99.     """Return true if the object is a data descriptor.
  100.  
  101.     Data descriptors have both a __get__ and a __set__ attribute.  Examples are
  102.     properties (defined in Python) and getsets and members (defined in C).
  103.     Typically, data descriptors will also have __name__ and __doc__ attributes
  104.     (properties, getsets, and members have both of these attributes), but this
  105.     is not guaranteed."""
  106.     return (hasattr(object, "__set__") and hasattr(object, "__get__"))
  107.  
  108. if hasattr(types, 'MemberDescriptorType'):
  109.     # CPython and equivalent
  110.     def ismemberdescriptor(object):
  111.         """Return true if the object is a member descriptor.
  112.  
  113.         Member descriptors are specialized descriptors defined in extension
  114.         modules."""
  115.         return isinstance(object, types.MemberDescriptorType)
  116. else:
  117.     # Other implementations
  118.     def ismemberdescriptor(object):
  119.         """Return true if the object is a member descriptor.
  120.  
  121.         Member descriptors are specialized descriptors defined in extension
  122.         modules."""
  123.         return False
  124.  
  125. if hasattr(types, 'GetSetDescriptorType'):
  126.     # CPython and equivalent
  127.     def isgetsetdescriptor(object):
  128.         """Return true if the object is a getset descriptor.
  129.  
  130.         getset descriptors are specialized descriptors defined in extension
  131.         modules."""
  132.         return isinstance(object, types.GetSetDescriptorType)
  133. else:
  134.     # Other implementations
  135.     def isgetsetdescriptor(object):
  136.         """Return true if the object is a getset descriptor.
  137.  
  138.         getset descriptors are specialized descriptors defined in extension
  139.         modules."""
  140.         return False
  141.  
  142. def isfunction(object):
  143.     """Return true if the object is a user-defined function.
  144.  
  145.     Function objects provide these attributes:
  146.         __doc__         documentation string
  147.         __name__        name with which this function was defined
  148.         func_code       code object containing compiled function bytecode
  149.         func_defaults   tuple of any default values for arguments
  150.         func_doc        (same as __doc__)
  151.         func_globals    global namespace in which this function was defined
  152.         func_name       (same as __name__)"""
  153.     return isinstance(object, types.FunctionType)
  154.  
  155. def isgeneratorfunction(object):
  156.     """Return true if the object is a user-defined generator function.
  157.  
  158.     Generator function objects provides same attributes as functions.
  159.  
  160.     See isfunction.__doc__ for attributes listing."""
  161.     return bool((isfunction(object) or ismethod(object)) and
  162.                 object.func_code.co_flags & CO_GENERATOR)
  163.  
  164. def isgenerator(object):
  165.     """Return true if the object is a generator.
  166.  
  167.     Generator objects provide these attributes:
  168.         __iter__        defined to support interation over container
  169.         close           raises a new GeneratorExit exception inside the
  170.                         generator to terminate the iteration
  171.         gi_code         code object
  172.         gi_frame        frame object or possibly None once the generator has
  173.                         been exhausted
  174.         gi_running      set to 1 when generator is executing, 0 otherwise
  175.         next            return the next item from the container
  176.         send            resumes the generator and "sends" a value that becomes
  177.                         the result of the current yield-expression
  178.         throw           used to raise an exception inside the generator"""
  179.     return isinstance(object, types.GeneratorType)
  180.  
  181. def istraceback(object):
  182.     """Return true if the object is a traceback.
  183.  
  184.     Traceback objects provide these attributes:
  185.         tb_frame        frame object at this level
  186.         tb_lasti        index of last attempted instruction in bytecode
  187.         tb_lineno       current line number in Python source code
  188.         tb_next         next inner traceback object (called by this level)"""
  189.     return isinstance(object, types.TracebackType)
  190.  
  191. def isframe(object):
  192.     """Return true if the object is a frame object.
  193.  
  194.     Frame objects provide these attributes:
  195.         f_back          next outer frame object (this frame's caller)
  196.         f_builtins      built-in namespace seen by this frame
  197.         f_code          code object being executed in this frame
  198.         f_exc_traceback traceback if raised in this frame, or None
  199.         f_exc_type      exception type if raised in this frame, or None
  200.         f_exc_value     exception value if raised in this frame, or None
  201.         f_globals       global namespace seen by this frame
  202.         f_lasti         index of last attempted instruction in bytecode
  203.         f_lineno        current line number in Python source code
  204.         f_locals        local namespace seen by this frame
  205.         f_restricted    0 or 1 if frame is in restricted execution mode
  206.         f_trace         tracing function for this frame, or None"""
  207.     return isinstance(object, types.FrameType)
  208.  
  209. def iscode(object):
  210.     """Return true if the object is a code object.
  211.  
  212.     Code objects provide these attributes:
  213.         co_argcount     number of arguments (not including * or ** args)
  214.         co_code         string of raw compiled bytecode
  215.         co_consts       tuple of constants used in the bytecode
  216.         co_filename     name of file in which this code object was created
  217.         co_firstlineno  number of first line in Python source code
  218.         co_flags        bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
  219.         co_lnotab       encoded mapping of line numbers to bytecode indices
  220.         co_name         name with which this code object was defined
  221.         co_names        tuple of names of local variables
  222.         co_nlocals      number of local variables
  223.         co_stacksize    virtual machine stack space required
  224.         co_varnames     tuple of names of arguments and local variables"""
  225.     return isinstance(object, types.CodeType)
  226.  
  227. def isbuiltin(object):
  228.     """Return true if the object is a built-in function or method.
  229.  
  230.     Built-in functions and methods provide these attributes:
  231.         __doc__         documentation string
  232.         __name__        original name of this function or method
  233.         __self__        instance to which a method is bound, or None"""
  234.     return isinstance(object, types.BuiltinFunctionType)
  235.  
  236. def isroutine(object):
  237.     """Return true if the object is any kind of function or method."""
  238.     return (isbuiltin(object)
  239.             or isfunction(object)
  240.             or ismethod(object)
  241.             or ismethoddescriptor(object))
  242.  
  243. def isabstract(object):
  244.     """Return true if the object is an abstract base class (ABC)."""
  245.     return isinstance(object, type) and object.__flags__ & TPFLAGS_IS_ABSTRACT
  246.  
  247. def getmembers(object, predicate=None):
  248.     """Return all members of an object as (name, value) pairs sorted by name.
  249.     Optionally, only return members that satisfy a given predicate."""
  250.     results = []
  251.     for key in dir(object):
  252.         value = getattr(object, key)
  253.         if not predicate or predicate(value):
  254.             results.append((key, value))
  255.     results.sort()
  256.     return results
  257.  
  258. Attribute = namedtuple('Attribute', 'name kind defining_class object')
  259.  
  260. def classify_class_attrs(cls):
  261.     """Return list of attribute-descriptor tuples.
  262.  
  263.     For each name in dir(cls), the return list contains a 4-tuple
  264.     with these elements:
  265.  
  266.         0. The name (a string).
  267.  
  268.         1. The kind of attribute this is, one of these strings:
  269.                'class method'    created via classmethod()
  270.                'static method'   created via staticmethod()
  271.                'property'        created via property()
  272.                'method'          any other flavor of method
  273.                'data'            not a method
  274.  
  275.         2. The class which defined this attribute (a class).
  276.  
  277.         3. The object as obtained directly from the defining class's
  278.            __dict__, not via getattr.  This is especially important for
  279.            data attributes:  C.data is just a data object, but
  280.            C.__dict__['data'] may be a data descriptor with additional
  281.            info, like a __doc__ string.
  282.     """
  283.  
  284.     mro = getmro(cls)
  285.     names = dir(cls)
  286.     result = []
  287.     for name in names:
  288.         # Get the object associated with the name.
  289.         # Getting an obj from the __dict__ sometimes reveals more than
  290.         # using getattr.  Static and class methods are dramatic examples.
  291.         if name in cls.__dict__:
  292.             obj = cls.__dict__[name]
  293.         else:
  294.             obj = getattr(cls, name)
  295.  
  296.         # Figure out where it was defined.
  297.         homecls = getattr(obj, "__objclass__", None)
  298.         if homecls is None:
  299.             # search the dicts.
  300.             for base in mro:
  301.                 if name in base.__dict__:
  302.                     homecls = base
  303.                     break
  304.  
  305.         # Get the object again, in order to get it from the defining
  306.         # __dict__ instead of via getattr (if possible).
  307.         if homecls is not None and name in homecls.__dict__:
  308.             obj = homecls.__dict__[name]
  309.  
  310.         # Also get the object via getattr.
  311.         obj_via_getattr = getattr(cls, name)
  312.  
  313.         # Classify the object.
  314.         if isinstance(obj, staticmethod):
  315.             kind = "static method"
  316.         elif isinstance(obj, classmethod):
  317.             kind = "class method"
  318.         elif isinstance(obj, property):
  319.             kind = "property"
  320.         elif (ismethod(obj_via_getattr) or
  321.               ismethoddescriptor(obj_via_getattr)):
  322.             kind = "method"
  323.         else:
  324.             kind = "data"
  325.  
  326.         result.append(Attribute(name, kind, homecls, obj))
  327.  
  328.     return result
  329.  
  330. # ----------------------------------------------------------- class helpers
  331. def _searchbases(cls, accum):
  332.     # Simulate the "classic class" search order.
  333.     if cls in accum:
  334.         return
  335.     accum.append(cls)
  336.     for base in cls.__bases__:
  337.         _searchbases(base, accum)
  338.  
  339. def getmro(cls):
  340.     "Return tuple of base classes (including cls) in method resolution order."
  341.     if hasattr(cls, "__mro__"):
  342.         return cls.__mro__
  343.     else:
  344.         result = []
  345.         _searchbases(cls, result)
  346.         return tuple(result)
  347.  
  348. # -------------------------------------------------- source code extraction
  349. def indentsize(line):
  350.     """Return the indent size, in spaces, at the start of a line of text."""
  351.     expline = string.expandtabs(line)
  352.     return len(expline) - len(string.lstrip(expline))
  353.  
  354. def getdoc(object):
  355.     """Get the documentation string for an object.
  356.  
  357.     All tabs are expanded to spaces.  To clean up docstrings that are
  358.     indented to line up with blocks of code, any whitespace than can be
  359.     uniformly removed from the second line onwards is removed."""
  360.     try:
  361.         doc = object.__doc__
  362.     except AttributeError:
  363.         return None
  364.     if not isinstance(doc, types.StringTypes):
  365.         return None
  366.     return cleandoc(doc)
  367.  
  368. def cleandoc(doc):
  369.     """Clean up indentation from docstrings.
  370.  
  371.     Any whitespace that can be uniformly removed from the second line
  372.     onwards is removed."""
  373.     try:
  374.         lines = string.split(string.expandtabs(doc), '\n')
  375.     except UnicodeError:
  376.         return None
  377.     else:
  378.         # Find minimum indentation of any non-blank lines after first line.
  379.         margin = sys.maxint
  380.         for line in lines[1:]:
  381.             content = len(string.lstrip(line))
  382.             if content:
  383.                 indent = len(line) - content
  384.                 margin = min(margin, indent)
  385.         # Remove indentation.
  386.         if lines:
  387.             lines[0] = lines[0].lstrip()
  388.         if margin < sys.maxint:
  389.             for i in range(1, len(lines)): lines[i] = lines[i][margin:]
  390.         # Remove any trailing or leading blank lines.
  391.         while lines and not lines[-1]:
  392.             lines.pop()
  393.         while lines and not lines[0]:
  394.             lines.pop(0)
  395.         return string.join(lines, '\n')
  396.  
  397. def getfile(object):
  398.     """Work out which source or compiled file an object was defined in."""
  399.     if ismodule(object):
  400.         if hasattr(object, '__file__'):
  401.             return object.__file__
  402.         raise TypeError('arg is a built-in module')
  403.     if isclass(object):
  404.         object = sys.modules.get(object.__module__)
  405.         if hasattr(object, '__file__'):
  406.             return object.__file__
  407.         raise TypeError('arg is a built-in class')
  408.     if ismethod(object):
  409.         object = object.im_func
  410.     if isfunction(object):
  411.         object = object.func_code
  412.     if istraceback(object):
  413.         object = object.tb_frame
  414.     if isframe(object):
  415.         object = object.f_code
  416.     if iscode(object):
  417.         return object.co_filename
  418.     raise TypeError('arg is not a module, class, method, '
  419.                     'function, traceback, frame, or code object')
  420.  
  421. ModuleInfo = namedtuple('ModuleInfo', 'name suffix mode module_type')
  422.  
  423. def getmoduleinfo(path):
  424.     """Get the module name, suffix, mode, and module type for a given file."""
  425.     filename = os.path.basename(path)
  426.     suffixes = map(lambda info:
  427.                    (-len(info[0]), info[0], info[1], info[2]),
  428.                     imp.get_suffixes())
  429.     suffixes.sort() # try longest suffixes first, in case they overlap
  430.     for neglen, suffix, mode, mtype in suffixes:
  431.         if filename[neglen:] == suffix:
  432.             return ModuleInfo(filename[:neglen], suffix, mode, mtype)
  433.  
  434. def getmodulename(path):
  435.     """Return the module name for a given file, or None."""
  436.     info = getmoduleinfo(path)
  437.     if info: return info[0]
  438.  
  439. def getsourcefile(object):
  440.     """Return the Python source file an object was defined in, if it exists."""
  441.     filename = getfile(object)
  442.     if string.lower(filename[-4:]) in ('.pyc', '.pyo'):
  443.         filename = filename[:-4] + '.py'
  444.     for suffix, mode, kind in imp.get_suffixes():
  445.         if 'b' in mode and string.lower(filename[-len(suffix):]) == suffix:
  446.             # Looks like a binary file.  We want to only return a text file.
  447.             return None
  448.     if os.path.exists(filename):
  449.         return filename
  450.     # only return a non-existent filename if the module has a PEP 302 loader
  451.     if hasattr(getmodule(object, filename), '__loader__'):
  452.         return filename
  453.  
  454. def getabsfile(object, _filename=None):
  455.     """Return an absolute path to the source or compiled file for an object.
  456.  
  457.     The idea is for each object to have a unique origin, so this routine
  458.     normalizes the result as much as possible."""
  459.     if _filename is None:
  460.         _filename = getsourcefile(object) or getfile(object)
  461.     return os.path.normcase(os.path.abspath(_filename))
  462.  
  463. modulesbyfile = {}
  464. _filesbymodname = {}
  465.  
  466. def getmodule(object, _filename=None):
  467.     """Return the module an object was defined in, or None if not found."""
  468.     if ismodule(object):
  469.         return object
  470.     if hasattr(object, '__module__'):
  471.         return sys.modules.get(object.__module__)
  472.     # Try the filename to modulename cache
  473.     if _filename is not None and _filename in modulesbyfile:
  474.         return sys.modules.get(modulesbyfile[_filename])
  475.     # Try the cache again with the absolute file name
  476.     try:
  477.         file = getabsfile(object, _filename)
  478.     except TypeError:
  479.         return None
  480.     if file in modulesbyfile:
  481.         return sys.modules.get(modulesbyfile[file])
  482.     # Update the filename to module name cache and check yet again
  483.     # Copy sys.modules in order to cope with changes while iterating
  484.     for modname, module in sys.modules.items():
  485.         if ismodule(module) and hasattr(module, '__file__'):
  486.             f = module.__file__
  487.             if f == _filesbymodname.get(modname, None):
  488.                 # Have already mapped this module, so skip it
  489.                 continue
  490.             _filesbymodname[modname] = f
  491.             f = getabsfile(module)
  492.             # Always map to the name the module knows itself by
  493.             modulesbyfile[f] = modulesbyfile[
  494.                 os.path.realpath(f)] = module.__name__
  495.     if file in modulesbyfile:
  496.         return sys.modules.get(modulesbyfile[file])
  497.     # Check the main module
  498.     main = sys.modules['__main__']
  499.     if not hasattr(object, '__name__'):
  500.         return None
  501.     if hasattr(main, object.__name__):
  502.         mainobject = getattr(main, object.__name__)
  503.         if mainobject is object:
  504.             return main
  505.     # Check builtins
  506.     builtin = sys.modules['__builtin__']
  507.     if hasattr(builtin, object.__name__):
  508.         builtinobject = getattr(builtin, object.__name__)
  509.         if builtinobject is object:
  510.             return builtin
  511.  
  512. def findsource(object):
  513.     """Return the entire source file and starting line number for an object.
  514.  
  515.     The argument may be a module, class, method, function, traceback, frame,
  516.     or code object.  The source code is returned as a list of all the lines
  517.     in the file and the line number indexes a line in that list.  An IOError
  518.     is raised if the source code cannot be retrieved."""
  519.     file = getsourcefile(object) or getfile(object)
  520.     module = getmodule(object, file)
  521.     if module:
  522.         lines = linecache.getlines(file, module.__dict__)
  523.     else:
  524.         lines = linecache.getlines(file)
  525.     if not lines:
  526.         raise IOError('could not get source code')
  527.  
  528.     if ismodule(object):
  529.         return lines, 0
  530.  
  531.     if isclass(object):
  532.         name = object.__name__
  533.         pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
  534.         # make some effort to find the best matching class definition:
  535.         # use the one with the least indentation, which is the one
  536.         # that's most probably not inside a function definition.
  537.         candidates = []
  538.         for i in range(len(lines)):
  539.             match = pat.match(lines[i])
  540.             if match:
  541.                 # if it's at toplevel, it's already the best one
  542.                 if lines[i][0] == 'c':
  543.                     return lines, i
  544.                 # else add whitespace to candidate list
  545.                 candidates.append((match.group(1), i))
  546.         if candidates:
  547.             # this will sort by whitespace, and by line number,
  548.             # less whitespace first
  549.             candidates.sort()
  550.             return lines, candidates[0][1]
  551.         else:
  552.             raise IOError('could not find class definition')
  553.  
  554.     if ismethod(object):
  555.         object = object.im_func
  556.     if isfunction(object):
  557.         object = object.func_code
  558.     if istraceback(object):
  559.         object = object.tb_frame
  560.     if isframe(object):
  561.         object = object.f_code
  562.     if iscode(object):
  563.         if not hasattr(object, 'co_firstlineno'):
  564.             raise IOError('could not find function definition')
  565.         lnum = object.co_firstlineno - 1
  566.         pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
  567.         while lnum > 0:
  568.             if pat.match(lines[lnum]): break
  569.             lnum = lnum - 1
  570.         return lines, lnum
  571.     raise IOError('could not find code object')
  572.  
  573. def getcomments(object):
  574.     """Get lines of comments immediately preceding an object's source code.
  575.  
  576.     Returns None when source can't be found.
  577.     """
  578.     try:
  579.         lines, lnum = findsource(object)
  580.     except (IOError, TypeError):
  581.         return None
  582.  
  583.     if ismodule(object):
  584.         # Look for a comment block at the top of the file.
  585.         start = 0
  586.         if lines and lines[0][:2] == '#!': start = 1
  587.         while start < len(lines) and string.strip(lines[start]) in ('', '#'):
  588.             start = start + 1
  589.         if start < len(lines) and lines[start][:1] == '#':
  590.             comments = []
  591.             end = start
  592.             while end < len(lines) and lines[end][:1] == '#':
  593.                 comments.append(string.expandtabs(lines[end]))
  594.                 end = end + 1
  595.             return string.join(comments, '')
  596.  
  597.     # Look for a preceding block of comments at the same indentation.
  598.     elif lnum > 0:
  599.         indent = indentsize(lines[lnum])
  600.         end = lnum - 1
  601.         if end >= 0 and string.lstrip(lines[end])[:1] == '#' and \
  602.             indentsize(lines[end]) == indent:
  603.             comments = [string.lstrip(string.expandtabs(lines[end]))]
  604.             if end > 0:
  605.                 end = end - 1
  606.                 comment = string.lstrip(string.expandtabs(lines[end]))
  607.                 while comment[:1] == '#' and indentsize(lines[end]) == indent:
  608.                     comments[:0] = [comment]
  609.                     end = end - 1
  610.                     if end < 0: break
  611.                     comment = string.lstrip(string.expandtabs(lines[end]))
  612.             while comments and string.strip(comments[0]) == '#':
  613.                 comments[:1] = []
  614.             while comments and string.strip(comments[-1]) == '#':
  615.                 comments[-1:] = []
  616.             return string.join(comments, '')
  617.  
  618. class EndOfBlock(Exception): pass
  619.  
  620. class BlockFinder:
  621.     """Provide a tokeneater() method to detect the end of a code block."""
  622.     def __init__(self):
  623.         self.indent = 0
  624.         self.islambda = False
  625.         self.started = False
  626.         self.passline = False
  627.         self.last = 1
  628.  
  629.     def tokeneater(self, type, token, srow_scol, erow_ecol, line):
  630.         srow, scol = srow_scol
  631.         erow, ecol = erow_ecol
  632.         if not self.started:
  633.             # look for the first "def", "class" or "lambda"
  634.             if token in ("def", "class", "lambda"):
  635.                 if token == "lambda":
  636.                     self.islambda = True
  637.                 self.started = True
  638.             self.passline = True    # skip to the end of the line
  639.         elif type == tokenize.NEWLINE:
  640.             self.passline = False   # stop skipping when a NEWLINE is seen
  641.             self.last = srow
  642.             if self.islambda:       # lambdas always end at the first NEWLINE
  643.                 raise EndOfBlock
  644.         elif self.passline:
  645.             pass
  646.         elif type == tokenize.INDENT:
  647.             self.indent = self.indent + 1
  648.             self.passline = True
  649.         elif type == tokenize.DEDENT:
  650.             self.indent = self.indent - 1
  651.             # the end of matching indent/dedent pairs end a block
  652.             # (note that this only works for "def"/"class" blocks,
  653.             #  not e.g. for "if: else:" or "try: finally:" blocks)
  654.             if self.indent <= 0:
  655.                 raise EndOfBlock
  656.         elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
  657.             # any other token on the same indentation level end the previous
  658.             # block as well, except the pseudo-tokens COMMENT and NL.
  659.             raise EndOfBlock
  660.  
  661. def getblock(lines):
  662.     """Extract the block of code at the top of the given list of lines."""
  663.     blockfinder = BlockFinder()
  664.     try:
  665.         tokenize.tokenize(iter(lines).next, blockfinder.tokeneater)
  666.     except (EndOfBlock, IndentationError):
  667.         pass
  668.     return lines[:blockfinder.last]
  669.  
  670. def getsourcelines(object):
  671.     """Return a list of source lines and starting line number for an object.
  672.  
  673.     The argument may be a module, class, method, function, traceback, frame,
  674.     or code object.  The source code is returned as a list of the lines
  675.     corresponding to the object and the line number indicates where in the
  676.     original source file the first line of code was found.  An IOError is
  677.     raised if the source code cannot be retrieved."""
  678.     lines, lnum = findsource(object)
  679.  
  680.     if ismodule(object): return lines, 0
  681.     else: return getblock(lines[lnum:]), lnum + 1
  682.  
  683. def getsource(object):
  684.     """Return the text of the source code for an object.
  685.  
  686.     The argument may be a module, class, method, function, traceback, frame,
  687.     or code object.  The source code is returned as a single string.  An
  688.     IOError is raised if the source code cannot be retrieved."""
  689.     lines, lnum = getsourcelines(object)
  690.     return string.join(lines, '')
  691.  
  692. # --------------------------------------------------- class tree extraction
  693. def walktree(classes, children, parent):
  694.     """Recursive helper function for getclasstree()."""
  695.     results = []
  696.     classes.sort(key=attrgetter('__module__', '__name__'))
  697.     for c in classes:
  698.         results.append((c, c.__bases__))
  699.         if c in children:
  700.             results.append(walktree(children[c], children, c))
  701.     return results
  702.  
  703. def getclasstree(classes, unique=0):
  704.     """Arrange the given list of classes into a hierarchy of nested lists.
  705.  
  706.     Where a nested list appears, it contains classes derived from the class
  707.     whose entry immediately precedes the list.  Each entry is a 2-tuple
  708.     containing a class and a tuple of its base classes.  If the 'unique'
  709.     argument is true, exactly one entry appears in the returned structure
  710.     for each class in the given list.  Otherwise, classes using multiple
  711.     inheritance and their descendants will appear multiple times."""
  712.     children = {}
  713.     roots = []
  714.     for c in classes:
  715.         if c.__bases__:
  716.             for parent in c.__bases__:
  717.                 if not parent in children:
  718.                     children[parent] = []
  719.                 children[parent].append(c)
  720.                 if unique and parent in classes: break
  721.         elif c not in roots:
  722.             roots.append(c)
  723.     for parent in children:
  724.         if parent not in classes:
  725.             roots.append(parent)
  726.     return walktree(roots, children, None)
  727.  
  728. # ------------------------------------------------ argument list extraction
  729. Arguments = namedtuple('Arguments', 'args varargs keywords')
  730.  
  731. def getargs(co):
  732.     """Get information about the arguments accepted by a code object.
  733.  
  734.     Three things are returned: (args, varargs, varkw), where 'args' is
  735.     a list of argument names (possibly containing nested lists), and
  736.     'varargs' and 'varkw' are the names of the * and ** arguments or None."""
  737.  
  738.     if not iscode(co):
  739.         raise TypeError('arg is not a code object')
  740.  
  741.     nargs = co.co_argcount
  742.     names = co.co_varnames
  743.     args = list(names[:nargs])
  744.     step = 0
  745.  
  746.     # The following acrobatics are for anonymous (tuple) arguments.
  747.     for i in range(nargs):
  748.         if args[i][:1] in ('', '.'):
  749.             stack, remain, count = [], [], []
  750.             while step < len(co.co_code):
  751.                 op = ord(co.co_code[step])
  752.                 step = step + 1
  753.                 if op >= dis.HAVE_ARGUMENT:
  754.                     opname = dis.opname[op]
  755.                     value = ord(co.co_code[step]) + ord(co.co_code[step+1])*256
  756.                     step = step + 2
  757.                     if opname in ('UNPACK_TUPLE', 'UNPACK_SEQUENCE'):
  758.                         remain.append(value)
  759.                         count.append(value)
  760.                     elif opname == 'STORE_FAST':
  761.                         stack.append(names[value])
  762.  
  763.                         # Special case for sublists of length 1: def foo((bar))
  764.                         # doesn't generate the UNPACK_TUPLE bytecode, so if
  765.                         # `remain` is empty here, we have such a sublist.
  766.                         if not remain:
  767.                             stack[0] = [stack[0]]
  768.                             break
  769.                         else:
  770.                             remain[-1] = remain[-1] - 1
  771.                             while remain[-1] == 0:
  772.                                 remain.pop()
  773.                                 size = count.pop()
  774.                                 stack[-size:] = [stack[-size:]]
  775.                                 if not remain: break
  776.                                 remain[-1] = remain[-1] - 1
  777.                             if not remain: break
  778.             args[i] = stack[0]
  779.  
  780.     varargs = None
  781.     if co.co_flags & CO_VARARGS:
  782.         varargs = co.co_varnames[nargs]
  783.         nargs = nargs + 1
  784.     varkw = None
  785.     if co.co_flags & CO_VARKEYWORDS:
  786.         varkw = co.co_varnames[nargs]
  787.     return Arguments(args, varargs, varkw)
  788.  
  789. ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults')
  790.  
  791. def getargspec(func):
  792.     """Get the names and default values of a function's arguments.
  793.  
  794.     A tuple of four things is returned: (args, varargs, varkw, defaults).
  795.     'args' is a list of the argument names (it may contain nested lists).
  796.     'varargs' and 'varkw' are the names of the * and ** arguments or None.
  797.     'defaults' is an n-tuple of the default values of the last n arguments.
  798.     """
  799.  
  800.     if ismethod(func):
  801.         func = func.im_func
  802.     if not isfunction(func):
  803.         raise TypeError('arg is not a Python function')
  804.     args, varargs, varkw = getargs(func.func_code)
  805.     return ArgSpec(args, varargs, varkw, func.func_defaults)
  806.  
  807. ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')
  808.  
  809. def getargvalues(frame):
  810.     """Get information about arguments passed into a particular frame.
  811.  
  812.     A tuple of four things is returned: (args, varargs, varkw, locals).
  813.     'args' is a list of the argument names (it may contain nested lists).
  814.     'varargs' and 'varkw' are the names of the * and ** arguments or None.
  815.     'locals' is the locals dictionary of the given frame."""
  816.     args, varargs, varkw = getargs(frame.f_code)
  817.     return ArgInfo(args, varargs, varkw, frame.f_locals)
  818.  
  819. def joinseq(seq):
  820.     if len(seq) == 1:
  821.         return '(' + seq[0] + ',)'
  822.     else:
  823.         return '(' + string.join(seq, ', ') + ')'
  824.  
  825. def strseq(object, convert, join=joinseq):
  826.     """Recursively walk a sequence, stringifying each element."""
  827.     if type(object) in (list, tuple):
  828.         return join(map(lambda o, c=convert, j=join: strseq(o, c, j), object))
  829.     else:
  830.         return convert(object)
  831.  
  832. def formatargspec(args, varargs=None, varkw=None, defaults=None,
  833.                   formatarg=str,
  834.                   formatvarargs=lambda name: '*' + name,
  835.                   formatvarkw=lambda name: '**' + name,
  836.                   formatvalue=lambda value: '=' + repr(value),
  837.                   join=joinseq):
  838.     """Format an argument spec from the 4 values returned by getargspec.
  839.  
  840.     The first four arguments are (args, varargs, varkw, defaults).  The
  841.     other four arguments are the corresponding optional formatting functions
  842.     that are called to turn names and values into strings.  The ninth
  843.     argument is an optional function to format the sequence of arguments."""
  844.     specs = []
  845.     if defaults:
  846.         firstdefault = len(args) - len(defaults)
  847.     for i in range(len(args)):
  848.         spec = strseq(args[i], formatarg, join)
  849.         if defaults and i >= firstdefault:
  850.             spec = spec + formatvalue(defaults[i - firstdefault])
  851.         specs.append(spec)
  852.     if varargs is not None:
  853.         specs.append(formatvarargs(varargs))
  854.     if varkw is not None:
  855.         specs.append(formatvarkw(varkw))
  856.     return '(' + string.join(specs, ', ') + ')'
  857.  
  858. def formatargvalues(args, varargs, varkw, locals,
  859.                     formatarg=str,
  860.                     formatvarargs=lambda name: '*' + name,
  861.                     formatvarkw=lambda name: '**' + name,
  862.                     formatvalue=lambda value: '=' + repr(value),
  863.                     join=joinseq):
  864.     """Format an argument spec from the 4 values returned by getargvalues.
  865.  
  866.     The first four arguments are (args, varargs, varkw, locals).  The
  867.     next four arguments are the corresponding optional formatting functions
  868.     that are called to turn names and values into strings.  The ninth
  869.     argument is an optional function to format the sequence of arguments."""
  870.     def convert(name, locals=locals,
  871.                 formatarg=formatarg, formatvalue=formatvalue):
  872.         return formatarg(name) + formatvalue(locals[name])
  873.     specs = []
  874.     for i in range(len(args)):
  875.         specs.append(strseq(args[i], convert, join))
  876.     if varargs:
  877.         specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
  878.     if varkw:
  879.         specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
  880.     return '(' + string.join(specs, ', ') + ')'
  881.  
  882. # -------------------------------------------------- stack frame extraction
  883.  
  884. Traceback = namedtuple('Traceback', 'filename lineno function code_context index')
  885.  
  886. def getframeinfo(frame, context=1):
  887.     """Get information about a frame or traceback object.
  888.  
  889.     A tuple of five things is returned: the filename, the line number of
  890.     the current line, the function name, a list of lines of context from
  891.     the source code, and the index of the current line within that list.
  892.     The optional second argument specifies the number of lines of context
  893.     to return, which are centered around the current line."""
  894.     if istraceback(frame):
  895.         lineno = frame.tb_lineno
  896.         frame = frame.tb_frame
  897.     else:
  898.         lineno = frame.f_lineno
  899.     if not isframe(frame):
  900.         raise TypeError('arg is not a frame or traceback object')
  901.  
  902.     filename = getsourcefile(frame) or getfile(frame)
  903.     if context > 0:
  904.         start = lineno - 1 - context//2
  905.         try:
  906.             lines, lnum = findsource(frame)
  907.         except IOError:
  908.             lines = index = None
  909.         else:
  910.             start = max(start, 1)
  911.             start = max(0, min(start, len(lines) - context))
  912.             lines = lines[start:start+context]
  913.             index = lineno - 1 - start
  914.     else:
  915.         lines = index = None
  916.  
  917.     return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
  918.  
  919. def getlineno(frame):
  920.     """Get the line number from a frame object, allowing for optimization."""
  921.     # FrameType.f_lineno is now a descriptor that grovels co_lnotab
  922.     return frame.f_lineno
  923.  
  924. def getouterframes(frame, context=1):
  925.     """Get a list of records for a frame and all higher (calling) frames.
  926.  
  927.     Each record contains a frame object, filename, line number, function
  928.     name, a list of lines of context, and index within the context."""
  929.     framelist = []
  930.     while frame:
  931.         framelist.append((frame,) + getframeinfo(frame, context))
  932.         frame = frame.f_back
  933.     return framelist
  934.  
  935. def getinnerframes(tb, context=1):
  936.     """Get a list of records for a traceback's frame and all lower frames.
  937.  
  938.     Each record contains a frame object, filename, line number, function
  939.     name, a list of lines of context, and index within the context."""
  940.     framelist = []
  941.     while tb:
  942.         framelist.append((tb.tb_frame,) + getframeinfo(tb, context))
  943.         tb = tb.tb_next
  944.     return framelist
  945.  
  946. if hasattr(sys, '_getframe'):
  947.     currentframe = sys._getframe
  948. else:
  949.     currentframe = lambda _=None: None
  950.  
  951. def stack(context=1):
  952.     """Return a list of records for the stack above the caller's frame."""
  953.     return getouterframes(sys._getframe(1), context)
  954.  
  955. def trace(context=1):
  956.     """Return a list of records for the stack below the current exception."""
  957.     return getinnerframes(sys.exc_info()[2], context)
  958.